[Mac] Gitbook in Mac
最近一直在思考如何学习 ，其中很重要的一环是输出。我曾经使用过语雀、思云等等，尽管它们功能丰富并且支持云端，但是对于像一本书一样阅读，这样的要求是达不到的，因此我选择了Gitbook + Githubpages
一、简单使用
Gitbook有网页版和本地版两种，网页版的功能感觉和语雀等类似，因此我选择本地版。你可以将本地版Gitbook（以下简称Gitbook）认为是一个工具链，这个工具链依赖于Node.js和npm。在mac的教程如下，windos看这个链接
1.安装
brew
在mac下需要先安装开发者工具brew,brew是一个类似apt、yum的包管理工具
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
安装完后命令行输入brew检查是否成功安装
npm
安装完brew后利用brew安装npm，npm是一个Node.js的包管理工具。我们需要用它来安装gitbook。
brew install npm
输入npm -v检查是否安装成功
nvm
nvm也是Node.js的版本管理工具，类似Python里面的conda。我们需要用它来管理Node.js的版本。
brew install nvm
输入nvm -v检查是否安装成功
gitbook
使用brew安装gitbook.-g选项的意思安装在全局，否则默认为安装在用户下。
brew install gitbook-cli -g
2.使用
初始化
选择一个你希望的空文件夹，初始化工作目录
# 初始化工作目录会生成 README.md 和 SUMMARY.md
gitbook init
# 构建工作会默认在 _book 下生成文件
gitbook build
# 服务器会构建本地端口映射
gitbook serve
执行gitbook init可能会出现的报错，如下
Installing GitBook 3.2.3
/opt/homebrew/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287
if (cb) cb.apply(this, arguments)
^
TypeError: cb.apply is not a function
at /opt/homebrew/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/graceful-fs/polyfills.js:287:18
at FSReqCallback.oncomplete (node:fs:200:5)
Node.js v21.0.0
这是因为 Node.js 的版本不符合 gitbook 的依赖，下面有三个可能的解决方法（推荐三）
注释
polyfills.js文件中的这三行fs.stat = statFix(fs.stat) fs.fstat = statFix(fs.fstat) fs.lstat = statFix(fs.lstat)升级
graceful-fs# 下面的路径换成你的，--save 的意思是安装在当前的本地，即为更新当前的 graceful-fs cd /opt/homebrew/lib/node_modules/gitbook-cli/node_modules/npm/node_modules/ npm install graceful-fs@latest --save通过
nvm来暂时降低Node.js版本nvm -v可能输出如下,箭头为当前的使用版本
$:nvm ls v21.0.0 -> system default -> node (-> v21.0.0) iojs -> N/A (default) unstable -> N/A (default) node -> stable (-> v21.0.0) (default) stable -> 21.0 (-> v21.0.0) (default) lts/* -> lts/hydrogen (-> N/A) lts/argon -> v4.9.1 (-> N/A) lts/boron -> v6.17.1 (-> N/A) lts/carbon -> v8.17.0 (-> N/A) lts/dubnium -> v10.24.1 lts/erbium -> v12.22.12 (-> N/A) lts/fermium -> v14.21.3 (-> N/A) lts/gallium -> v16.20.2 (-> N/A) lts/hydrogen -> v18.18.2 (-> N/A)我们需要安装
10.24.1的版本,注意该段命令会只是会将当前的shell下的Node.js切换成10.24.1。#Install a specific version number nvm install 10.24.1 #Use the latest available 8.0.x nvm use 10.21.1
二、入门进阶
1.配置文件
SUMMERY.md
一份参考文件如下，这个文件的内容会被用来生成大纲。
[]()的超链接用来表示标题，
----会生成分隔符
# Summary的不是必要的，也不会被显示
## Chapter1会被显示，但是不如超链接好用，一般只用超链接
# Summary
## Chapter1
* [Part I](part1/README.md)
* [Writing is nice](part1/README.md#writing)
* [GitBook is nice](part1/README.md#gitbook)
* [Part II](part2/README.md)
* [We love feedback](part2/README.md#feedback)
* [Better tools for authors](part2/README.md#tools)
----
* [Last part without title](part3/title.md)
book.json
你可以新建一个book.json的配置文件，参考内容如下
{
"title": "title",
"description": "description",
"isbn": "isbn",
"author": "author",
"lang": "zh-cn",
"plugins": [],
"variables": {
}
}
你可以修改plugins来加入插件,search插件支持中文搜索，code插件支持复制,-的意思是不使用该插件，需要使用可以去掉前面的-
plugins": ['code','-seacrh']
然后利用gitbook install来安装上面的插件
gitbook install
插件可以配置属性
pluginsConfig: {
"flexible-alerts": {
style: "flat" // callout 或 flat
}
}
2.插件推荐
{
plugins: ['expandable-chapters'];
}
{
plugins: ['back-to-top-button'];
}
{
plugins: ['flexible-alerts'];
pluginsConfig: {
"flexible-alerts": {
style: "flat" // callout 或 flat
}
}
}
引用插件语法
> [!NOTE]
> Information the user should notice even if skimming.
> [!TIP]
> Optional information to help a user be more successful.
（这个似乎无效）
> [!IMPORTANT]
> Essential information required for user success.
（这个似乎无效）
> [!CAUTION]
> Negative potential consequences of an action.
> [!WARNING]
> Dangerous certain consequences of an action.
[!NOTE] Information the user should notice even if skimming.
分隔符
[!TIP] Optional information to help a user be more successful.
分隔符
[!WARNING] Dangerous certain consequences of an action.
拓展玩法：自定义引用 有关图标可以在这里寻找
//自定义类型，className可能有info,warning,tip,note
pluginsConfig: {
"flexible-alerts": {
style: "flat" // callout 或 flat
"comment": {
"label": "Comment",
"icon": "fa fa-comments",
"className": "info"
}
}
}
[!Comment] Dangerous certain consequences of an action.
[引用插件]
{
plugins: ['alerts'];
}
效果如下，支持info，waring，danger，successs
> **[info] For info**
>
> Use this for infomation messages.
[info] For info
Use this for infomation messages.
> **[warning] For warning**
>
> Use this for warning messages.
[warning] For warning
Use this for warning messages.
> **[danger] For danger**
>
> Use this for danger messages.
[danger] For danger
Use this for infomation messages
> **[success] For success**
>
> Use this for success messages.
[success] For success
Use this for success messages.
mathjax有问题，总是安装不了，无意间发现了katex可以直接安装
{
"plugins": ["katex"]
}
三、深入探索
Github Pages
在github上新建一个仓库，新建个gh-page分支，在github设置支持静态网页的pages。然后我们可以将这个仓库克隆下来，初始化gitbook。不过值得注意的是github只是支持选择/和/docs这两个路径作为网页根目录。因此我们选择/docs，这样的话适合gitbook.
调整gitbook仓库的目录如下,根路径下的README.md作为仓库的说明，book下的README.md作为书籍首页的说明。book可以修改为你喜欢的名字。
.
├── README.md
├── book
│ ├── README.md
│ ├── SUMMARY.md
│ ├── book.json
└── docs
同时我们需要修改gitbook命令参数，可以尝试执行如下命令
# 安装book下book.json的插件
gitbook install book
# gitbook build src dest
gitbook build book docs
# gitbook serve src dest
gitbook serve book docs
执行后的示例目录
.
├── README.md
├── bash.sh
├── book
│ ├── Gitbook Explore in Mac
│ ├── How to write markdown elegantly
│ ├── README.md
│ ├── SUMMARY.md
│ ├── book.json
│ └── node_modules
└── docs
├── Gitbook Explore in Mac
├── How to write markdown elegantly
├── gitbook
├── index.html
├── search_index.json
└── search_plus_index.json
自动化脚本
我构建的一份自动更新上传脚本如下，前两行是为了在bash中使用nvm
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # 加载 nvm
nvm use 10
gitbook install book
gitbook build book docs
git add .
git commit -m "Update"
git push
gitbook serve book docs
输出文档
问题合集
gitbook install 出问题
使用下面的替代
npm install gitbook-plugin-*
gitbook install